Create a object with a name of objName. The special object name #auto indicates that the name of the object is defined by the struct package and the generated value is returned as the result of the struct_new call. The type must be a valid type. If a third argument is specified, then the object references an existing data area, otherwise a new memory buffer is created and initialized to binary zeros.
The object is created as a Tcl array with a name of objName. A Tcl variable trace is placed on the array to implement access to the C structure. The object will be removed when it is either explicitly unset(n) or when leaving the scope of objName.
An object cannot be passed by value to a procedure since it is created as a Tcl array. The upvar(n) command should be used when passing an object by reference. The script struct_show(n) is a good example of how this can be done.
The #auto cannot be used to create a global instance of an object. Creation of a global object with a unique name can be done with a sequence of four commands: set objname [struct_new #auto type] global $objname unset $objname struct_new $objname type
Structure objects may be references in one of two ways: using an objName created by struct_new, or using a typed pointer.
An object reference using an objName looks to Tcl like
an array reference.
objName(string)
TclStruct uses a trace procedure to parse the string
find the part of the object being referred to. The string
consists of zero or more parts, each separated by a period '.' .
Each part is read in sequence (starting at the left) and is used
to modify the reference to the object. The following are the
valid parts:
The degenerate form "objName()" is used to refer to the whole object. When passed to a TclStruct command, an object reference can be passed without the '()'s.
Typed pointers are not managed by
the TclStruct package, but may be created on the fly to refer
to data allocated elsewhere. A typed pointer has the format
typeName#address
where typeName is the name of a defined type, and address
is the decimal address in memory where the data resides.
To create an array of 10 integers:
The following example demonstrates the use of pointers and de-referencing
various fields:
struct_typedef extype {struct
{char*8 name}
{ushort flags}
{ushort count}
{^extype next}
}
struct_new first extype struct_new last extype
# Initialize the structures set first() {first 22 1 last()} set last() {last 17 3 0}
# Access portions puts "first = $first()" puts "first.name = $first(name)" puts "last = $last()" puts "last = $first(next.)" puts "last.count = $first(next.count)" puts "last.name.1 = $first(next.name.1)" puts "last = $first(next.._hex_)" The output is first = {first 22 1 extype#134745056} first.name = first last = {last 17 3 0} last = {last 17 3 0} last.count = 3 last.name.1 = a last = 6c617374000000001100030000000000
User traces placed on the array or its elements are not guaranteed to work in a consistent fashion.
No management is done on the third argument. It is the users responsibility to prevent dangling pointers caused by removal of the original object.